Resource Standard Metrics (c)1996-1997, M Squared Technologies, All Rights Reserved. RSM provides a standard metrics tool for all of your C and C++ projects across today's popular operating systems, including Windows 3.1/95/NT and UNIX. ~ Features ~ - Provides code line count, logical complexity, code style and functional analysis. - Counts lines of code, comments, blanks, logical and physical lines. - Calculates percentages of code, comments and white space. - Performs project, file, functional and macro analysis. - Analyzes source code against common coding practices. - Analyzes source code for quality problems - Analyzes C source for C++ compatibility - Allows the user to customize applicable coding practices with minimum levels of comments and white space allowable within the code. - Simple command line interface with parameter switches for variable output ranging from summary lists to verbose reports. - Provides memory function counts for memory allocation and de-allocation analysis. - Allows the user to see how the tool determines LOC counts against the given source code. - Source code printing/documentation with line numbers, margins, header, and file date/time. - Completely portable across all UNIX compatible operating systems, Windows 95/NT/dpmi DOS compiled with DJGPP(gcc) 2.0. - Pre-compiled for Windows 95/NT/dpmi DOS. Source is easily compiled on any UNIX ANSI C compiler. - Paid source licenses come with source code for portability across all compatible operating systems, with money back guarantee for cross compilation. Provided source code may not be altered or transferred. ~ Compilation and Installation ~ The source code file rsm.c is provided so that it may be recompiled on your system. The file rsm.c is compilable on any UNIX ANSI C compiler and DJGPP 2.0 for Win95/NT/DOS shell mode. The source files provided on the DOS format diskette might need to be converted into a UNIX file format if they are to be used on a UNIX like system. If during UNIX compilation, your compiler complains of invalid white space character or bad syntax for directive, the source file needs to be converted to a UNIX format. This conversion can be easily accomplished using a DOS2UNIX command. We have provided source code which can be used to create such a tool. This source is called dos2unix.c. You are advised to use the UNIX tar diskette on a UNIX machine and the DOS formatted diskette on a DOS/Windows machine. The source provide is known NOT to compile on Visual C++ or Borland C++. You must use DJGPP 2.0 for DOS/Windows compilation. To acquire the FREE DJGPP compiler for recompilation, look up our web page located at the URL: http://207.92.81.101/se.htm For RSM support and documentation please reference the rsm Web site at the URL: http://207.92.81.101/rsm.htm UNIX Installation Place the diskette in your machine's local floppy drive and execute the following commands. % mkdir rsm % cd rsm % tar -xvf /dev/fd0 or for the *.tar.gz distribution % gunzip rsm.tar.gz % tar -xvf rsm.tar The source files will be extracted from the tar format diskette. DOS/Windows Installation Place the diskette in your machine’s local floppy drive and execute the following commands. C:\> mkdir rsm C:\> cd rsm C:\> copy a:\*.* The source files will be copied to the rsm directory. Note: rsm.exe is a 32 Bit program. It will run naturally on Windows 95 and Windows NT. However, under Windows 3.1 and DOS a dpmi 32 bit extender must be used. Such an extender is called cwsdpmi.exe and is located on the source diskette. This executable must be found in your system path. For example: C:\> copy cwsdpmi.exe c:\dos. Compiling RSM and RSMCL Unix ANSI Posix C Compiler gcc -O3 -o rsm rsm.c gcc -O3 -o rsmcl rsmcl.c -lm DJGPP 2.0+ for Win95/NT and DOS gcc -O3 -DDOS -o rsm rsm.c gcc -O3 -DDOS -o rsm rsmcl.c -lm Solaris cc -o rsm rsm.c cc -o rsmcl rsmcl.c -lm HPUX cc -Aa -D_INCLUDE_POSIZ_SOURCE -o rsm rsm.c cc -Aa -D_INCLUDE_POSIZ_SOURCE -o rsmcl rsmcl.c -lm ~ Use and Operation ~ Resource Standard Metrics is run from the command line of any shell window such as a DOS shell window in Windows 95/NT or UNIX xterm. RSM takes a series of switches which define its behavior and a list of file specifications which include file wild cards. However, the shareware version of RSM processes one file at a time, thus eliminating the capability to process wild card file specifications and summarize for files and projects. Syntax: RSM <-acdfhlmnqsv> filename or wild cards Start using RSM by specifying the -h switch. This will produce a very useful help text. Read this information carefully as it will detail how to customize the operation of RSM. Switches are designed to be cumulative for adding behavior to the operation of the tool. The following switches should be used in a singular fashion as their output is not complementary with the general RSM reporting structure. RSM supported long file names (LFN) in UNIX and Windows 95. NT uses a 32 bit FAT and different file system than Windows 95. RSM will process NT source file but it will represent the filenames in the 8.3 file name format. The user will have to transpose these file names by hand back to there original name. Release 3.0 of RSM will support LFN for NT. Run Time Switch Options The options shown with a * can be aggregated together to form compound reports. Some experimentation will be required to find the combination of options which yield the desired report Common useage: ie. normal with wild cards: rsm -facmnv *.c *.cc recursive descent: rsm -facmnv -r c,cc,h,hh /proj read a file list: rsm -facmnv -F filelist.txt Allocation/De-allocation of Memory Mode* ------------------------------------------------------------------------ -a Produces metrics on memory creation through the counting of instances of malloc, calloc, realloc and new. Memory de-allocation is measured by counting free and delete. This metrics is useful for focusing in on functions which dynamically manage memory. Most program bugs can be attributed to dynamic memory management. ie. rsm -a *.c Benchmark Mode* ------------------------------------------------------------------------ -b This mode tracks the CPU, User, Wait and elapsed time for the running of RSM. This mode is intended to create a timing metric for RSM so that the time require to execute the systems metrics is known. It may also serve as a benchmark for comparing RSM to other like products, although no other products are known which have as many features as RSM. ie. rsm -b *.c Complexity Mode* ------------------------------------------------------------------------ -c This mode measures both cyclomatic complexity and comparative complexity. Cyclomatic complexity is consistent with McCabes definition and yields results similar to other tools like Cadre's Ensemble in about 1,000th of the time. Cyclomatic complexity counts every while and if and adds 1 for the instance of a function. Comparative complexity measures the comparisons within the while's and if's to indicate the degree of tests used in the branching. Functions with either high cyclomatic or comparative complexity should be more thoroughly tested during unit tests. ie. rsm -c *.c *.h Cyclomatic complexity is calculated by the sum of; 1 for the function construct plus the number of instances of keywords for while, if, goto and case. Cyclomatic complexity is a measure of branching or paths within a module. A Cyclomatic complexity of 10 or greater is very susceptible to problematic behavior and should be thoroughly unit tested. Comparative complexity is calculated by the sum of the number of instances of comparison and logical test operators ( &&, ||, !=, ==, <=, >=, <, > ) within the test conditions for each 'if' and 'while'. Comparative complexity can be used to determine the degree of complexity of branching decisions. If a module has a cyclomatic complexity of 12 and a comparative complexity of 30, the module has branching decisions which are composed of at least two tests or conditions per branch which indicates 30 test cases require to completely test this module. Functional complexity is calculated by the sum of cyclomatic (logical) complexity and comparative complexity. The maximum and average complexity is reported for the file and for all files processed. Deterministic Mode ------------------------------------------------------------------------ -d This mode will show the user a line of source and how RSM determines whether the line is code or comment. Too often metrics tools yield code lines and comment lines equal to the physical lines measured. RSM accounts for comments and code on a single line and counts two logical lines. RSM also measure effective code by eliminating the lines of code which contain just { } or ( ). ie. rsm -d source.c This mode produces the validation of the given source against the LOC algorithm of Resource Standard Metrics. Output will echo each line of code and a state of the LOC determination. Example Output: Line 1: /* functions using pointers to functions */ LOC Type(s): Line 2: LOC Type(s): Line 3: #include /*standard includes*/ LOC Type(s): Line 4: #include // more includes LOC Type(s): Function Analysis Mode* ------------------------------------------------------------------------ -f Function mode determines the functions in the source and if quality NOTICES are on, it will perform quality checking on the functions. Modes -f and -n are usually used together. ie. rsm -f *.c File List Mode* ------------------------------------------------------------------------ -F Will process files from a file list. This mode is useful for performing a discrete set of file metrics. The list must be a text file with on literal filename on each line. ie. rsm -fac -F filelist.txt File Format: filelist.txt ./src/control.c ./src/display.c ./inc/control.h ./inc/display.h Note that no wild cards are valid in this mode. Help Mode ------------------------------------------------------------------------ -h Produces the help output. Such output can be printed under UNIX by piping the output to lpr or redirecting if to a file. UNIX: rsm -h | lpr rsm -h > help.txt DOS/W95/NT: rsm -h > prn rsm -h > help.txt Identify Class Mode* ------------------------------------------------------------------------ -i This mode will identify C++ class names to the report. The class definition line is shown on the report helping to identify class names, template classes and inheritance. This information is helpful when assessing the complexity of a system. ie. rsm -i *.cc *.hh List Function Name Mode ------------------------------------------------------------------------ -l This mode produces a list of functions which can be cut and pasted from the output into the comment header of the file which was processed. It will create a report where all function names are correlated with their parent file. This is usesful when documenting the system. ie. rsm -l *.cc *.c Example Output: Function: Show Function: Drawable::Drawable Function: Drawable::Show Macro Mode* ------------------------------------------------------------------------ -m Macro mode is similar to function mode except it reports the names of the macros within the source. Macros are a common cause of maintenance and portability headaches so locating their existence is quite valuable. ie. rsm -fm *.c Quality Notice Mode* ------------------------------------------------------------------------ -n Turns on quality checking for the source for approximately 40 common problems which create difficult maintenance, porting or semantic bugs the compiler simply misses. ie. rsm -facmn *.cc *.c *.cpp Query Configuration Mode ------------------------------------------------------------------------ -q Prompts the user for which quality notices should be included into the -n analysis. The query for each quality notice effects the the value of the environment variable which sets the quality states. ie. rsm -q Example Output: Notice Current State ------------------------------------------------------------------ Check for line lengths > 80 characters. On Activate this notification? [y/n]: y Check for function names > 32 characters. On Activate this notification? [y/n]: n The results create a numeric value which must be set into the environment of the shell which operates the RSM tool. To set an environment variable in UNIX it is best to set the environment variable from the .cshrc or .login file. For the c shell: setenv RSMNOTICE 31748. To set the environment variable in DOS, set the value in the autoexec.bat file. set RSMNOTICE=31748 Recursive Descent Mode* ------------------------------------------------------------------------ -r Recursive descent mode will process all the specified files from a given point in the directory tree. A file spec must be specified as a list of file extensions separated by commas. The starting point must be a directory. ie. rsm -r rsm -facr c,cpp ./proj rsm -f -a -c -r cc,c,h,hh ../mysrc rsm -vr c c:\srcs Recursive File List Mode ------------------------------------------------------------------------ -R Generates a list of all file which will be processed in the recursive descent. This list may be cut from the report to provide a project file inventory. ie. rsm -Rr c,h,cc,hh . rsm -R -r c,cpp .\proj Summary Mode* ------------------------------------------------------------------------ -s Summary mode summarizes the LOC and comments per file. ie. rsm -facmns *.c rsm *.c "default if no option specified" Terse Output Mode* ------------------------------------------------------------------------ -t Terse output generates a summary report which can be parsed by scripting languages such as Pearl. Each data line has the following syntax: keyword: data ... ie. rsm -t *.c *.cc Example Output: File: timer.c LoC: 87 eLoc: 66 Comments: 2 Blanks: 16 Lines: 105 Totals Only Mode* ------------------------------------------------------------------------ -T This mode only displays grand totals for all files processed. In this mode, other reporting data is suppressed. This mode makes it easy to determine grand totals for your project. ie. rsm -T *.c *.cc rsm -Tr c,h c:\src rsm -Tvr c ./project Verbose Mode* ------------------------------------------------------------------------ -v Verbose output show many metrics for each file and a grand total for all files. This mode provides many different numbers which the user can interpret. ie. rsm -facmnv *.cpp *.c License Agreement Mode: ------------------------------------------------------------------------ -z License Agreement Mode: Shows the software/source code license agreement which the user and company are bound to by using RSM. Long File Names Long file names are directly supported through the command line in the UNIX and Windows 95 operating systems. The Windows NT DOS shell interpreter does not serve up long file names from the command line. RSM will process the NT long file names where the file names are transformed into the 8(char).3(char) format. NT LFN support will be provided in the JAVA version of RSM. Code Quality Analysis The following quality conditions are analyzed with the -fn switch. These switches will analyze each function for compliance with standard coding practices and common errors sometimes missed by compilers or present in questionable design. Latent Code Problems: ------------------------------------------------------------------------ NOTICE: Line 317, '...' ellipsis found for a variable argument list. The compiler will not check the types of these parameters. NOTICE: Identified a Non-ANSI function prototype. Function parameters will not be type checked. NOTICE: All 'switch conditions do not have a matching 'default'. This could cause unexpected behavior if the switch condition is not met by the available case statements. NOTICE: All 'case' conditions do not have a matching 'break'. This condition can occur when sequential case statements are used. Check this function to insure no erroneous behavior will occur by an unexpected drop through to the next case statement. NOTICE: Line 532, a pre-increment '++' identified within a MACRO. This syntax is non-portable and is NOT recommended within macro definitions. NOTICE: Line 544, pre-increment '++' identified. This can be a problematic construct in compound statements. NOTICE: Line 557, a pre-decrement '--' identified within a MACRO. This syntax is non-portable and is NOT recommended within macro definitions. NOTICE: Line 569, pre-decrement '--' identified. This can be a problematic construct in compound statements. NOTICE: Line 585, '=' assignment identified within an 'if' condition. This is an indication of a compound statement or suggest use of an '==' equivalence test. NOTICE: Line 590, '=' assignment identified within a 'while' condition. This is an indication of a compound statement or suggest use of an '==' equivalence test. NOTICE: Line 612, The '?' operator was identified. This implied if-else construct is very problematic in it's syntax and use. NOTICE: Line 913, realloc has been identified. A realloc of 0 size will free the pointer. This may cause an unanticipated action on a NULL pointer. Portability and Maintainability Issues: ------------------------------------------------------------------------ NOTICE: Line 234, The keyword, 'if', appears not to be delimited with scope { .. } operators around its content. This could cause a maintenance problem where code falls outside the intended scope of the 'if' statement. NOTICE: Line 244, The keyword, 'else', appears not to be delimited with scope { .. } operators around its content. This could cause a maintenance problem where code falls outside the intended scope of the 'else' statement. NOTICE: Line 254, The keyword, 'for', appears not to be delimited with scope { .. } operators around its content. This could cause a maintenance problem where code falls outside the intended scope of the 'for' statement. NOTICE: Line 264, The keyword, 'while', appears not to be delimited with scope { .. } operators around its content. This could cause a maintenance problem where code falls outside the intended scope of the 'while' statement. NOTICE: Line 274, The keyword, 'do', appears not to be delimited with scope { .. } operators around its content. This could cause a maintenance problem where code falls outside the intended scope of the 'do' statement. NOTICE: The function name 'Show_List_From_Database_Optical_Parts' length 37 is greater than 32 characters long. This can be a portability and/or maintenance issue. NOTICE: Brackets, [ ] are not balanced. The compiler should have caught this error. This notice may indicate dead code within the source commented out through a #define construct NOTICE: Parenthesis, ( ) are not balanced. The compiler should have caught this error. This notice may indicate dead code within the source commented out through a #define construct NOTICE: Line 417, friend class 'Graphics' identified. This is a problematic construct as it breaks encapsulation. NOTICE: Line 734, 'goto' keyword identified. This can cause maintenance difficulties and propagate hidden logic flow. C to C++ Migration Analysis ------------------------------------------------------------------------ The following ANSI C++ keywords are checked in C files to ensure the C source code can be migrated to C++. This mode can be disabled using the -q option for the configuration of rsm. ANSI C++ Keywords additional to ANSI C Syntax: ---------------------------------------------- asm bool catch class const_cast delete dynamic_cast false friend inline mutable namespace new operator overload private protected public reinterpret_cast static_cast template this throw true try typeid using virtual wchar_t NOTICE: Line 5, An ANSI C++ keyword 'asm' has been found within a C file. This will cause a compile error if this file is compiled with a C++ compiler. It is suggested that this symbol name be changed to a non-conflicting name for C to C++ migration. Code Understandability Analysis ------------------------------------------------------------------------ NOTICE: Line 311, Line character length = 92. This width exceeds the standard terminal width of 80 characters. NOTICE: Lines of Code, LOC, in this function exceed the specified standard of 200 lines. NOTICE: Function comments, 7.4% are less than 10%. NOTICE: Function white space, 3.3% is less than 10%. NOTICE: File comment line percentage, 2.3% is less than 10% NOTICE: File white space percentage, 4.3% is less than 10% Miscellaneous Notifications ------------------------------------------------------------------------ NOTICE: File does not contain the key string specified in the environment variable RSMKEYSTR. Key String: You may customize the notification boundaries for Comment Percentage, White space percentage and maximum lines per function (module) by specifying the following environment variables Specify which notices to check '-q' - setenv RSMNOTICE 7340031 Specify a key string for CM control - setenv RSMKEYSTR "@(#)Ver" Comment Percentage per file/function - setenv RSMCOMMENT 10 White space percentage per file/function - setenv RSMWHITE 10 Maximum Lines per function (module) - setenv RSMLINES 200 Common Modes: The switches are listed below and create a variety of output. Running RSM without any switches creates plain LOC summaries as output. We can suggest a few modes which we routinely use. RSM -facmv *.c ..\*.h This mode produces the most information without any quality notices. -f creates functional analysis. -a produces memory allocation and de-allocation counts. -c produces complexity measures. -m produces an output of any macro defined in the source. -v produces verbose output of keywords and constructs. RSM -facmvn *.c ..\*.h Adds quality notices to the above specification. Remember you turn on and off notices by using the -q option and the RSMNOTICE memory variable. Analysis limits for comment, white space, and lines per module are determined by the following defaults or changed by the following environment variables: Defaults: Minimum comments per function = 10% Minimum comments per file = 10% Lines Comments Comment Percent = ----------------------- * 100 Lines (Comments + Code) Lines Code Code Percent = ----------------------- * 100 Lines (Comments + Code) Blank Characters White Space = ------------------ * 100 Total Characters To set the comment percentage per file or function use the environment variable RSMCOMMENT. The following specifies the file and function comment percent to 25 percent. UNIX csh: setenv RSMCOMMENT 25 DOS/W95/NT: set RSMCOMMENT=25 To set the white space percentage per file or function use the environment variable RSMWHITE. The following specifies the file and function white space content percentage to 5 percent. UNIX csh: setenv RSMWHITE 5 DOS/W95/NT: set RSMWHITE=5 To set the maximum lines per function, specify the environment variable RSMLINES. The following sets the maximum line of code per function to 500 lines of code. UNIX csh: setenv RSMLINES 500 DOS/W95/NT: set RSMLINES=500 There may be instances where each source file must contain a specific string and you would like RSM to check for the occurrence of this string. This condition is appropriate for a copyright notice, security markings or version string for configuration management. To specify the string for RSM to look for, specify the environment variable RSMKEYSTR. To specify the string "(C) 1997 Acme Software". UNIX csh: setenv RSMKEYSTR "(C) 1997 Acme Software" DOS/W95/NT: set RSMKEYSTR="(C) 1997 Acme Software" Make sure that the quality notice for the key string is ON and the -n switch is specified. ~ Product History ~ M Squared Technologies recognized the need for a good tool to help assess source code quickly and accurately. This tool needed to assess code for complexity, quantity, and quality against common coding practices. This tool would be used for subcontract evaluation, code peer reviews, budgeting/estimations, and for quality certifications. The assessment had to be standardized across all common operating systems. We searched the Internet for a tool with the ability to analyze code and produce information about the lines of code, percentage of comments, amount of white space, and the use of keywords and constructs. Additional requirements were the capability to indicate a degree of complexity, and to analyze the code for compliance with common coding practices while also detecting common errors which cause poor quality code. The code analysis tool must analyze both C and C++ source code. Our search for the ultimate tool found many which could meet some of these requirements, but not all, and they were usually bound to one operating system. Standardization of metrics and code analysis for ISO 9001 compliance, across all of our projects and operating systems appeared hopeless. The key requirement, that the tool be easily compiled on any operating system, seemed to be a discriminating factor. The tool also needed to be easily compiled by novice programmers (students), and be built as easily as "cc -o filename filename.c". After using many available tools with confusing interfaces and terse reports, we decided on a requirement that a source code analysis tool must have a simple interface and produce reports in varying formats to meet the need of the user. Such output should range from simple summaries to verbose reports. Ultimately, we determined that if we wanted a tool to meet all of our requirements, we would have to build it ourselves. The result is Resource Standard Metrics, or RSM. RSM was created using ANSI C as the programming language and basic UNIX commands for file access. This allows the tool to be freely compiled on most UNIX operating systems and Linux. This design decision also allows the code to be compiled with DJGPP 2.0, a 32 bit, gcc port for dpmi DOS, Windows 95 and Windows NT. The program, though complex, was built into a single C file, eliminating the need for make files and the make utility. Simplicity and portability are the primary objectives. There are many programs which count lines of code, but none indicate how the lines of code are determined in reference to the individual lines in the source code. Users are left with a LOC number and they would have no idea how the program examined the code. RSM will show you how it examines your source when used with the -d option. RSM accounts correctly for code and comments on the same physical line which generates logical lines of code. Many programmers place { or ( on a single line. As this practice makes code easy to read, it can artificially increase source lines of code metrics. RSM creates a measure of eLOC or effective lines of code which is the metrics of LOC minus lines of just { or ( . LOC, eLOC, logical line, physical line and code statements are presented for your choice in metrics. Some programmers prefer the code statement approach. Code statements or lines terminated with semi-colons, excluding the one addition statement in loops. All of these metrics are displayed in the verbose mode with the -v option. RSM has been successfully compiled using gcc or DJGPP 2.0 on such operating systems as HP-UX, Solaris, Sun OS, Linux, dpmi DOS, Windows 95 and NT. ~ Technical Support ~ Please provide a full description, example source code and print outs for reporting bugs and technical suggestions. Please email your request to out technical support group. They will provide a 24 hour turn around on all email requests. Tech Support M Squared Technologies 2128 Hidden Pine Lane Apopka, FL 32712 Email - m2tech@reachus.com Phone/Fax - (407) 880-2627 Web Site - http://207.92.81.101 M Squared Technologies Software/Source Code License Agreement As a licensee of our products you are legally bound by this license agreement, its terms and conditions. The software, source code and documentation which you have/will acquired is the legal intellectual property of M Squared Technologies and is protected by the copyright laws of the United States and international copyright treaties. The possession and use of this Software and Documentation is subject to the restrictions contained in this license agreement. You, the LICENSEE, are licensed to the type of license identified under LICENSE. This license is nontransferable to any other party other than the LICENSEE. License Type: Commercial License - Single User or License Type: Network License - Multiple User The source code provided with this software is for recompilation only. You may NOT modify, print, publish, sell, give away or distribute this source code in any manner, shape or form. Failure to comply to this provision will void this License agreement, product support and result in prosecution. M Squared Technologies reserves all rights not expressly granted to the licensee. General Terms This License will become effective on the date you acquire the Software and will remain in force until terminated. You may terminate this License at any time by destroying the Documentation, Source Code and all binary executables, object code or images built from said source, together with all copies and adaptations. This License shall automatically terminate if you breach any of the terms or conditions. You agree to destroy the original and all copies of the Software and Documentation, or return them to M Squared Technologies upon termination of the License. Governing Laws Except as otherwise restricted by law, this License shall be governed by, and interpreted in accordance with, the laws of the State of Florida of the United States of America, without regard to Laws of Florida governing conflicts of law. Furthermore, it is understood that this License shall be treated as though it were executed in the State of Florida. The parties agree that any action relating to this License shall be prosecuted in the courts of competent jurisdiction of the State of Florida. Entire License This License sets forth the entire understanding of the License between you and M Squared Technologies and may be amended only in writing by both parties. No vendor, distributor, dealer, retailer, sales person or other person is authorized to modify this License or to make any warranty, representation, or promise which is different than, or in addition to, the representations or promises of this license. M Squared Technologies